home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / concepts / mysql < prev    next >
Text File  |  2001-06-18  |  7KB  |  193 lines
  1. CONCEPT
  2.             mysql - mySQL support
  3.  
  4. DESCRIPTION
  5.         On hosts with the mySQL package installed, the driver can be
  6.         configured to interface with the mySQL database. If that is done,
  7.         the driver defines the macro __MYSQL__ for LPC programs and
  8.         activates a number of efuns.
  9.  
  10.         -- Configuration --
  11.         
  12.         Create a dedicated user in the mySQL database for the driver.
  13.         Enter this username and password in the file pkg-mysql.c, function
  14.         mysql_real_connect(), and compile the driver (the username and
  15.         password are built into the driver for security reasons).
  16.         If you chose to not create either a username and/or a password,
  17.         leave the corresponding entry at 0.
  18.  
  19.         Use mysqladmin to create any databases you want to provide - the
  20.         names are later used in the efun db_connect() to connect to
  21.         the databases.
  22.  
  23.  
  24.         -- Usage --
  25.  
  26.         The idea behind SQL-support is that you can swap large amounts of
  27.         data into a database where it can be accessed very easily.
  28.         As mySQL "limits" the number of connections to 100 and as every
  29.         connection to the mySQL-server takes time, you should use
  30.         database serverobjects in your MUD which constantly keep the
  31.         connection to the mySQL-server.
  32.  
  33.         To connect to your mySQL-server, use the efun db_connect(). It
  34.         takes only one argument which is the name of the database (which
  35.         must exist).  The return-value of db_connect() is an integer
  36.         representing the unique handle to the database with which you will
  37.         identify your connection later.
  38.  
  39.         To send or retrieve data from this connection, use db_exec(). The
  40.         first parameter for all efuns dealing with an open connection is
  41.         always the handle and so is the first argument the handle and the
  42.         second one the command you want to issue. The return-value is
  43.         either 0 if there was an error in your command (this can have
  44.         various reasons), otherwise your handle is returned again. A typical
  45.         SQL-statement to retrieve data would be like this:
  46.         
  47.                 select aliases.command from aliases where (name = 'mario' AND
  48.                   alias regexp 'l.*')
  49.  
  50.         As you know, mySQL accepts either " or ' to classify strings for
  51.         parameters.  Most likely, you will pass variables and don't know
  52.         whether they contain one or more of these key-chars (or even other
  53.         chars that need to be converted). mySQL provides a function for
  54.         converting just any string into an acceptable argument and this is
  55.         implemented in db_conv_string().
  56.  
  57.         So the above example with variables looks like this:
  58.  
  59.                 select aliases.command from aliases where (name ='"+
  60.                   db_conv_string(name)+"' AND alias regexp '"+
  61.                   db_conv_string(mask)+"')
  62.  
  63.         I left out the db_exec()-stuff, more complete examples will follow.
  64.  
  65.         After you initiated a statement that should return rows from the
  66.         database, use db_fetch() to retrieve the data. db_fetch() returns
  67.         the data row by row and not all at once. You need to call it until
  68.         it returns 0. THIS IS IMPORTANT! If stop calling db_fetch() before
  69.         it reaches the end of data, serious inconsistencies can happen.
  70.  
  71.         If you used a DELETE- or UPDATE-statement, you cannot call db_fetch(),
  72.         but you might be interested in the number of deleted/changed rows
  73.         which can be queried with db_affected_rows().
  74.  
  75.         After all operations are done in the database, you should use
  76.         db_close() to close the connection again. If you are using a
  77.         database-server-concept, place it in the remove()-function.
  78.  
  79.         The SQL-efuns have some built-in optimization-features to speed up
  80.         often used connections. To get a list of all open connections to the
  81.         mySQL-server, use db_handles() which returns an array of integers
  82.         with all open handles.
  83.  
  84.  
  85. EXAMPLE
  86.         A simple server to store aliases could be implemented like this:
  87.  
  88.         /*
  89.         **  CREATION:
  90.         **
  91.         **  create table aliases (
  92.         **      name varchar(15) not NULL,
  93.         **      alias varchar(20) not NULL,
  94.         **      command varchar(255) not NULL,
  95.         **      primary key (name, alias));
  96.         */
  97.  
  98.         #define DATABASE "mud"
  99.  
  100.         private int handle;
  101.  
  102.         public void create()
  103.         {
  104.             handle = db_connect(DATABASE);
  105.         }
  106.  
  107.         public int remove()
  108.         {
  109.             if ( handle )
  110.                 db_close(handle);
  111.             destruct(ME);
  112.             return !ME;
  113.         }
  114.  
  115.         public int AddAlias(string alias, string command, object ob)
  116.         {
  117.             if ( !handle )
  118.                 handle = db_connect(DATABASE);
  119.             if ( !db_exec(handle,
  120.                           "insert into aliases (name, alias, command) values "
  121.                           "('" + getuid(ob) + "','" + db_conv_string(alias)
  122.                                + "','"+
  123.                           db_conv_string(command) + "')") )
  124.                 return -1;
  125.             return 1;
  126.         }
  127.  
  128.         public int RemoveAlias(string alias, object ob)
  129.         {
  130.             int res;
  131.  
  132.             if ( !handle )
  133.                 handle = db_connect(DATABASE);
  134.             res = db_exec(handle,
  135.                           "delete from aliases where (name = '"+
  136.                           getuid(ob) + "' AND alias = '"
  137.                                      + db_conv_string(alias)+
  138.                           "')");
  139.             if ( !res )
  140.                 return 0;
  141.             res = db_affected_rows(handle);
  142.             return (res > 0)?1:-1;
  143.         }
  144.  
  145.         public mixed *QueryAliases(string mask, object ob)
  146.         {
  147.             mixed *result;
  148.             string *tmp;
  149.  
  150.             if ( !handle )
  151.                 handle = db_connect(DATABASE);
  152.             if ( !db_exec(handle,
  153.                           "select aliases.alias, aliases.command from aliases where "
  154.                           "(name = '" + getuid(ob)+
  155.                           "' AND alias regexp '" + db_conv_string(mask) + "')") )
  156.                 return ({ });
  157.             result = ({ });
  158.             while ( sizeof(tmp = db_fetch(handle)) )
  159.                 result += ({ tmp });
  160.             return result;
  161.         }
  162.  
  163.         public string QueryAlias(string alias, object ob)
  164.         {
  165.             mixed *result;
  166.             string *tmp;
  167.  
  168.             if ( !handle )
  169.                 handle = db_connect(DATABASE);
  170.             if ( !db_exec(handle,
  171.                           "select aliases.command from aliases where "
  172.                           "(name = '" + getuid(ob)+
  173.                           "' AND alias = '" + db_conv_string(alias) + "')") )
  174.                 return 0;
  175.             result = ({ });
  176.             while ( sizeof(tmp = db_fetch(handle)) )
  177.                 result += tmp;
  178.             return sizeof(result)?result[0]:0;
  179.         }
  180.  
  181.  
  182. AUTHOR
  183.         Mark Daniel Reidel and others.
  184.  
  185. HISTORY
  186.         mySQL support was added as a package in 3.2.8 and became and
  187.         integral driver part in 3.2.9.
  188.  
  189. SEE ALSO
  190.         db_affected_rows(E), db_conv_string(E), db_close(E),
  191.         db_connect(E), db_exec(E), db_fetch(E), db_handles(E),
  192.         db_insert_id(E), db_coldefs(E), db_error(E)
  193.